home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / libraries / rtlibrary.lha / rtlibrary / rtlibrary.readme
Encoding:
Text File  |  1995-02-01  |  3.5 KB  |  99 lines
  1. short: A kind of "resource tracking" makes cleanup easier.
  2. type: dev/c
  3. uploader: too@cs.hut.fi
  4. author: Tomi Ollila <too@cs.hut.fi>
  5.  
  6. This library is public domain. Use it any way you want. I do :)
  7. No warranty of any kind is given.
  8.  
  9. Rt library provides a way to "remember" what resources has been allocated 
  10. for the task a program is doing. Then, at the end of program execution, one
  11. `delete' -call will go through a stack of allocated stuff and call their
  12. corresponding deallocation functions.
  13.  
  14. The initial and final procedures one must do are quite simple:
  15.  
  16. First, create an rt memory space. Currently this space is statically bound
  17. to the value programmer gives. Programmer must know/quess a value high
  18. enough for all stuff that rt must remember: This is done the following way:
  19.  
  20.     struct RT * rt;
  21.  
  22.     unless (rt = rt_Create(100)) /* #define unless(x) if (!(x)) */
  23.        return 20;
  24.  
  25. This allocates memory for 100 items that rt can remember.
  26.  
  27. ...Now you can for example do the following thing (and then forget the
  28. thing alltogether):
  29.  
  30.     void closeLib(struct Library * base) { CloseLibrary(base); }
  31. ...
  32.  
  33.     unless (DOSBase = (struct DosLibrary *)OpenLibrary("dos.library", 37))
  34.        return 20;
  35.  
  36.     rt_Add(rt, closeLib, DOSBase);
  37.  
  38. but all this can be done easier by using the provided rt_CloseLib -function:
  39.  
  40.     unless (rt_CloseLib(rt, &DOSBase, "dos.library", 37))
  41.        return 20;
  42.  
  43.  
  44. As you see, the rt -system takes a pointer to deallocation function and a
  45. data pointer to be given as an argument to that function. At the end of
  46. program execution, the following call will do all these deallocation
  47. function calls in reverse order they were installed.
  48.  
  49. rt_Delete(rt);
  50.  
  51.  
  52. The library in current state provides the following functions:
  53.  
  54. /* rt.c */
  55. struct RT * rt_Create(int size); /* creates an rt instance */
  56. struct RTNode * rt_Add(struct RT * rt, void * func, void * data);
  57. struct RTNode * rt_Delete(struct RT * rt);
  58.  
  59. /* rt_remnode.c -- the function below deletes one node */
  60. void rt_RemNode(struct RT * rt, struct RTNode * node);
  61.  
  62. /* rt_remdata.c -- the function below deletes one node searched by data ptr */
  63. void rt_Remdata(struct RT * rt, void * data);
  64.  
  65. /* rt_remsome.c -- function deletes multiple entries ... */
  66. void rt_Remdata(struct RT * rt, void * ptr, ULONG flags);
  67.  
  68. /* rt_exec/rt_openlib.c -- void * as libptr reduces compiler warnings */
  69. struct RTNode * rt_OpenLib(struct RT * rt, void * libptr, 
  70.                 char * name, int version); */
  71.  
  72. /* rt_exec/rt_allocmem.c -- void * as memptr reduces compiler warnings */
  73. struct RTNode * rt_AllocMem(struct RT * rt, void * memptr,
  74.                 ULONG size, ULONG flags);
  75.  
  76. /* rt_dos/rt_open.c */
  77. struct RTNode * rt_Open(struct RT * rt, BPTR * file, char * name, int mode);
  78.  
  79.  
  80. See the test program in test directory of this archive. It demonstrates
  81. the way those rt_Rem* -functions work (1384 bytes long and it uses almost
  82. all the functions provided in the library). 
  83.  
  84. If you want to add your own rt functions to this library, please follow the
  85. convention I've been using in rt_exec/ and rt_dos/ directories. I will gladly
  86. add all your "wrappers" you want to be included in this public distribution
  87. of this library.
  88.  
  89. All sources and this library is compiled w/ gcc only, since it was so easy
  90. to use gcc cross compiler at sun sparcstation while developing this library
  91. (21" monitor, X and Emacs19 rules).
  92.  
  93. Well, This documentation should give you a start of trying and using this
  94. library. Please send me comments about the usability and everything you
  95. could think about this piece of work to the address too@cs.hut.fi.
  96.  
  97. Tomi
  98.  
  99.